import SEO from "../components/SEO";

<SEO
  title="Image"
  description="The Image component is used to display images."
/>

# Image

The Image component is used to display images.

Image composes `CBox` so you can use all the style props and add responsive
styles as well.

<carbon-ad />

## Import

```js
import { CImage } from "@chakra-ui/vue";
```

## Usage

```vue live=true
<c-box w="sm">
  <c-image src="https://bit.ly/chakra-jonathan-bakebwa" alt="Jonathan Bakebwa" />
</c-box>
```

## Size

The size of the image can be adjusted using the `size` prop.

```vue live=true
<c-stack is-inline>
  <c-image
    size="100px"
    objectFit="cover"
    src="https://bit.ly/sage-adebayo"
    alt="Segun Adebayo"
  />
  <c-image
    size="150px"
    objectFit="cover"
    src="https://bit.ly/chakra-naruto-uzumaki"
    alt="Naruto Uzumaki"
  />
  <c-image size="200px" src="https://bit.ly/chakra-sarah-drasner" alt="Sarah Drasner" />
</c-stack>
```

## Rounded Image

```vue live=true
<c-image
  rounded="full"
  h="150px"
  w="150px"
  src="https://bit.ly/chakra-jonathan-bakebwa"
  alt="Jonathan Bakebwa"
/>
```

## Using relative paths
In a Vue CLI project, you might find that using relative assets doesn't load the image paths
correctly in Chakra's image components.

This is because `vue-loader` converts relative paths like `@/assets/path-to-img.jpg` into `require` functions
automatically for you at build time. Unfortunately, this is not the case when it comes to custom
components from an installed component library like Chakra UI Vue.

You can circumvent this issue by using `require('@/assets/path-to-img.jpg')`.
Below is the correct way to `require` relative assets for the `CImage` and `CAvatar` components.

```vue
<!-- ❌ Incorrect -->
<c-image src="@/assets/path-to-img.jpg" />

<!-- ✅ Correct -->
<c-image :src="require('@/assets/path-to-img.jpg')" />
```

## Fallback support

You can provide a fallback image for when there is an error loading the `src` of
the image. You can also opt-out of this behavior by passing the `ignoreFallback`
prop.

```vue live=true
<c-image src="gibberish.png" fallback-src="https://via.placeholder.com/150" />
```

| Name             | Type               | Default | Description                                                                                                                  |
| ---------------- | ------------------ | ------- | ---------------------------------------------------------------------------------------------------------------------------- |
| `src`            | `string`           |         | The path to the image source                                                                                                 |
| `fallbackSrc`    | `string`           |         | In event there was an error loading the `src`, specify a fallback. In most cases, this can be an avatar or image placeholder |
| `alt`            | `string`           |         | The alt text that describes the image                                                                                        |
| `onLoad`         | `function`         |         | A callback for when the image `src` has been loaded                                                                          |
| `onError`        | `function`         |         | A callback for when there was an error loading the image `src`                                                               |
| `htmlWidth`      | `string`, `number` |         | The native HTML width attribute of the `img` element                                                                         |
| `htmlHeight`     | `string`, `number` |         | The native HTML height attribute of the `img` element                                                                        |
| `ignoreFallback` | `boolean`          |         | Opt out of the `fallbackSrc` logic and use the `Image` directly                                                              |

## Events

| Name       | Payload   | Description                                                                                                  |
| ---------- | --------- | ------------------------------------------------------------------------------------------------------------ |
| `@load`    | `-`       | The event emitted when the image `src` has been loaded                                                    |
| `@error`   | `-`       | The event emitted when an error occurs when loading the image `src`                                           |
